1 /** 2 * Constructs a new label mark with default properties. Labels are not typically 3 * constructed directly, but by adding to a panel or an existing mark via 4 * {@link pv.Mark#add}. 5 * 6 * @class Represents a text label, allowing textual annotation of other marks or 7 * arbitrary text within the visualization. The character data must be plain 8 * text (unicode), though the text can be styled using the {@link #font} 9 * property. If rich text is needed, external HTML elements can be overlaid on 10 * the canvas by hand. 11 * 12 * <p>Labels are positioned using the box model, similarly to {@link Dot}. Thus, 13 * a label has no width or height, but merely a text anchor location. The text 14 * is positioned relative to this anchor location based on the 15 * {@link #textAlign}, {@link #textBaseline} and {@link #textMargin} properties. 16 * Furthermore, the text may be rotated using {@link #textAngle}. 17 * 18 * <p>Labels ignore events, so as to not interfere with event handlers on 19 * underlying marks, such as bars. In the future, we may support event handlers 20 * on labels. 21 * 22 * <p>See also the <a href="../../api/Label.html">Label guide</a>. 23 * 24 * @extends pv.Mark 25 */ 26 pv.Label = function() { 27 pv.Mark.call(this); 28 }; 29 30 pv.Label.prototype = pv.extend(pv.Mark) 31 .property("text") 32 .property("font") 33 .property("textAngle") 34 .property("textStyle") 35 .property("textAlign") 36 .property("textBaseline") 37 .property("textMargin") 38 .property("textShadow"); 39 40 pv.Label.prototype.type = "label"; 41 42 /** 43 * The character data to render; a string. The default value of the text 44 * property is the identity function, meaning the label's associated datum will 45 * be rendered using its <tt>toString</tt>. 46 * 47 * @type string 48 * @name pv.Label.prototype.text 49 */ 50 51 /** 52 * The font format, per the CSS Level 2 specification. The default font is "10px 53 * sans-serif", for consistency with the HTML 5 canvas element specification. 54 * Note that since text is not wrapped, any line-height property will be 55 * ignored. The other font-style, font-variant, font-weight, font-size and 56 * font-family properties are supported. 57 * 58 * @see <a href="http://www.w3.org/TR/CSS2/fonts.html#font-shorthand">CSS2 fonts</a> 59 * @type string 60 * @name pv.Label.prototype.font 61 */ 62 63 /** 64 * The rotation angle, in radians. Text is rotated clockwise relative to the 65 * anchor location. For example, with the default left alignment, an angle of 66 * Math.PI / 2 causes text to proceed downwards. The default angle is zero. 67 * 68 * @type number 69 * @name pv.Label.prototype.textAngle 70 */ 71 72 /** 73 * The text color. The name "textStyle" is used for consistency with "fillStyle" 74 * and "strokeStyle", although it might be better to rename this property (and 75 * perhaps use the same name as "strokeStyle"). The default color is black. 76 * 77 * @type string 78 * @name pv.Label.prototype.textStyle 79 * @see pv.color 80 */ 81 82 /** 83 * The horizontal text alignment. One of:<ul> 84 * 85 * <li>left 86 * <li>center 87 * <li>right 88 * 89 * </ul>The default horizontal alignment is left. 90 * 91 * @type string 92 * @name pv.Label.prototype.textAlign 93 */ 94 95 /** 96 * The vertical text alignment. One of:<ul> 97 * 98 * <li>top 99 * <li>middle 100 * <li>bottom 101 * 102 * </ul>The default vertical alignment is bottom. 103 * 104 * @type string 105 * @name pv.Label.prototype.textBaseline 106 */ 107 108 /** 109 * The text margin; may be specified in pixels, or in font-dependent units (such 110 * as ".1ex"). The margin can be used to pad text away from its anchor location, 111 * in a direction dependent on the horizontal and vertical alignment 112 * properties. For example, if the text is left- and middle-aligned, the margin 113 * shifts the text to the right. The default margin is 3 pixels. 114 * 115 * @type number 116 * @name pv.Label.prototype.textMargin 117 */ 118 119 /** 120 * A list of shadow effects to be applied to text, per the CSS Text Level 3 121 * text-shadow property. An example specification is "0.1em 0.1em 0.1em 122 * rgba(0,0,0,.5)"; the first length is the horizontal offset, the second the 123 * vertical offset, and the third the blur radius. 124 * 125 * @see <a href="http://www.w3.org/TR/css3-text/#text-shadow">CSS3 text</a> 126 * @type string 127 * @name pv.Label.prototype.textShadow 128 */ 129 130 /** 131 * Default properties for labels. See the individual properties for the default 132 * values. 133 * 134 * @type pv.Label 135 */ 136 pv.Label.prototype.defaults = new pv.Label() 137 .extend(pv.Mark.prototype.defaults) 138 .text(pv.identity) 139 .font("10px sans-serif") 140 .textAngle(0) 141 .textStyle("black") 142 .textAlign("left") 143 .textBaseline("bottom") 144 .textMargin(3); 145